package org.dreamwork.jasmine2.restful.annotation;

import org.dreamwork.jasmine2.restful.MethodType;

import java.lang.annotation.*;

/**
 * 定义一个类以及类的方法为一个 Restful API 实例及接口方法.
 *
 * Created with IntelliJ IDEA.
 * @author seth.yang
 * Date: 14-11-21
 * Time: 下午4:50
 */
@Target ({ElementType.TYPE, ElementType.METHOD})
@Retention (RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface RestfulAPI {
    String DEFAULT_VALUE = "";

    /**
     * Restful API 标题
     * @return Restful API 标题
     */
    String title ();

    /**
     * Restful API 映射，默认和 <code>类</code> 或 <code>方法</code> 同名
     * @return Restful API 映射
     */
    String pattern () default DEFAULT_VALUE;

    /**
     * Restful API 描述
     * @return Restful API 描述
     */
    String description () default DEFAULT_VALUE;

    /**
     * 强制加密.
     *
     * 若 Restful API 被定义为强制加密，则 Restful API 调用时<strong>将强制检查数据是否加密</strong>，
     * 若数据未加密，则返回 ENCRYPT_REQUIRED 错误
     * @return 是否强制加密
     */
    boolean forceEncrypt () default false;

    /**
     * 允许的 HTTP 方法
     * @return HTTP 方法类型
     */
    MethodType method () default MethodType.GET;

    /**
     * 定义所有的 Context Parameter.
     *
     * Context Parameter 指的是，全局传输的参数，这些参数将出现在 API URL 的 Query String 部分，
     * 且在 Restful API 被调用时，系统会尝试注入到 API 实例对象内.
     *
     * 如果 Context Parameter 被指定为必须的，系统在调用前还将会验证这些必须的参数
     * @return Context Parameter 列表
     */
    ContextParameter[] contextParameters() default {};

    /**
     * 定义 Restful API 返回对象的参考结构.
     *
     * Restful API 返回值的真正结构和这个定义无关。
     *
     * @return Restful API 的参考返回结构
     */
    ResultField[] result() default  {};

    /**
     * 参数列表.
     *
     * 定义出入的参数列表。
     * 如果该处不定义，<strong>必须在方法签名上定义每个参数</strong>
     * @return 传入参数列表
     */
    APIParameter[] apiParameters () default {};

    /**
     * 是否跳过 API 执行前的动作.
     *
     * 该动作由 @BeforeExecute 标注指定.
     *
     * 只有 @RestfulAPI 标注用于方法时，该属性才有效，如果是 @RestfulAPi 用于标注类，则忽略该属性
     * @return 是否跳过 API 执行前的动作.
     */
    boolean skipBeforeExecute () default false;

    boolean forceJson () default false;
}